<?php
/**
 * CONTENIDO extension pack (mpContenidoX), consists of multiple classes to
 * provide more features for Plugins/Modules.
 *
 * @package     mpContenidoX
 * @subpackage  Security
 * @author      Murat Purc <murat@purc.de>
 * @copyright   Copyright (c) 2008-2012 Murat Purc (http://www.purc.de)
 * @license     http://www.gnu.org/licenses/gpl-2.0.html - GNU General Public License, version 2
 * @version     $Id: mpFilter.class.php 21 2012-07-16 21:33:14Z purcaholic $
 */


defined('CON_FRAMEWORK') or die('Illegal call');


/**
 * Wrapper for the filter* functions, which are available since PHP 5.2.0 and are
 * enabled by default.
 *
 * The filter extension provides functions to valiadate and sanitize data.
 *
 * See http://www.php.net/manual/en/book.filter.php for more details.
 *
 * This class has wrapper for following filter functions:
 * - filter_has_var:     Checks if variable of specified type exists
 * - filter_id:          Returns the filter ID belonging to a named filter
 * - filter_input_array: Gets external variables and optionally filters them
 * - filter_input:       Gets a specific external variable by name and optionally filters it
 * - filter_list:        Returns a list of all supported filters
 * - filter_var_array:   Gets multiple variables and optionally filters them
 * - filter_var:         Filters a variable with a specified filter
 *
 * TODO: implement fallback, if filter functions are not available
 *
 * @package     mpContenidoX
 * @subpackage  Security
 * @author      Murat Purc <murat@purc.de>
 */
class mpFilter
{

    /**
     * Self instance
     * @var  mpFilter
     */
    protected static $_instance = null;


    /**
     * Initializes the mpFilter instance, tries to set PHP configuration with defined filter
     * settings, if possible!
     *
     * @return  void
     */
    protected function __construct()
    {
        global $cfg; // damn globals...

        // takeover configuration, see http://www.php.net/manual/en/filter.configuration.php
        if (isset($cfg['filter.default']) && !empty($cfg['filter.default'])) {
            @ini_set('filter.default', $cfg['filter.default']);
        }
        if (isset($cfg['filter.default_flags']) && !empty($cfg['filter.default_flags'])) {
            @ini_set('filter.default_flags', $cfg['filter.default_flags']);
        }
    }


    /**
     * Returns self instance as a singleton
     *
     * @return  mpFilter
     */
    public static function getInstance()
    {
        if (self::$_instance == null) {
            self::$_instance = new self();
        }
        return self::$_instance;
    }


    /**
     * Wrapper for filter_has_var().
     * Checks if variable of specified type exists.
     *
     * @link  http://www.php.net/manual/en/function.filter-has-var.php
     *
     * @param   int     $type  One of INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER, INPUT_ENV
     * @param   string  $name  Name of variable to check
     * @return  bool
     */
    public function hasVar($type, $name)
    {
        return filter_has_var($typ, $name);
    }


    /**
     * Wrapper for filter_id().
     * Returns the filter ID belonging to a named filter.
     *
     * @link  http://www.php.net/manual/en/function.filter-id.php
     *
     * @param   string  $name  Name of a filter to get
     * @return  int|null  ID of a filter on success or NULL if filter doesn't exist
     */
    public function id($name)
    {
        return filter_id($name);
    }


    /**
     * Wrapper for filter_input_array().
     * Gets external variables and optionally filters them.
     *
     * @link  http://www.php.net/manual/en/function.filter-input-array.php
     *
     * @param   int  $type  One of INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER, INPUT_ENV,
     *                      INPUT_SESSION (not implemented yet), or INPUT_REQUEST (not implemented yet).
     * @param   mixed  $definition  An array defining the arguments. A valid key is a string containing
     *                              a variable name and a valid value is either a filter type, or an
     *                              array optionally specifying the filter, flags and options. If the
     *                              value is an array, valid keys are filter which specifies the filter
     *                              type, flags which specifies any flags that apply to the filter, and
     *                              options which specifies any options that apply to the filter.
     *
     *                              This parameter can be also an integer holding a filter constant.
     *                              Then all values in the input array are filtered by this filter.
     * @return  mixed  An array containing the values of the requested variables on success, or FALSE
     *                 on failure. An array value will be FALSE if the filter fails, or NULL if the
     *                 variable is not set. Or if the flag FILTER_NULL_ON_FAILURE  is used, it returns
     *                 FALSE if the variable is not set and NULL if the filter fails.
     */
    public function inputArray($type, $definition = array())
    {
        return filter_input_array($type, $definition);
    }


    /**
     * Wrapper for filter_input().
     * Gets a specific external variable by name and optionally filters it.
     *
     * @link  http://www.php.net/manual/en/function.filter-input.php
     *
     * @param   int  $type  One of INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER, INPUT_ENV,
     *                      INPUT_SESSION (not implemented yet), or INPUT_REQUEST (not implemented yet).
     * @param   string  $name  Name of a variable to get.
     * @param   int     $filter  Filter to apply.
     * @param   mixed   $options  Associative array of options or bitwise disjunction of flags.
     *                            If filter accepts options, flags can be provided in "flags" field of array.
     * @return  mixed  Value of the requested variable on success, FALSE if the filter fails, or NULL
     *                 if the variable_name  variable is not set. If the flag FILTER_NULL_ON_FAILURE
     *                 is used, it returns FALSE if the variable is not set and NULL  if the filter fails.
     */
    public function input($type, $name, $filter = FILTER_DEFAULT, $options = array())
    {
        return filter_input($type, $name, $filter, $options);
    }


    /**
     * Wrapper for filter_list().
     * Returns a list of all supported filters.
     *
     * @link  http://www.php.net/manual/en/function.filter-list.php
     *
     * @return  array  Returns an array of names of all supported filters, empty array if
     *                 there are no such filters. Indexes of this array are not filter IDs,
     *                 they can be obtained with filter_id() from a name instead.
     */
    public function getList()
    {
        return filter_list();
    }


    /**
     * Wrapper for filter_var_array().
     * Gets multiple variables and optionally filters them.
     *
     * @link  http://www.php.net/manual/en/function.filter-var-array.php
     *
     * @param   array  $data  An array with string keys containing the data to filter.
     * @param   mixed  $definition  An array defining the arguments. A valid key is a string containing a
     *                              variable name and a valid value is either a filter type, or an array
     *                              optionally specifying the filter, flags and options. If the value is
     *                              an array, valid keys are filter which specifies the filter type, flags
     *                              which specifies any flags that apply to the filter, and options which
     *                              specifies any options that apply to the filter. See the example below
     *                              for a better understanding.
     *                              This parameter can be also an integer holding a filter constant. Then
     *                              all values in the input array are filtered by this filter.
     * @return  mixed  An array containing the values of the requested variables on success, or FALSE on
     *                 failure. An array value will be FALSE if the filter fails, or NULL if the variable
     *                 is not set.
     */
    public function varArray(array $data, $definition = array())
    {
        return filter_var_array($data, $definition);
    }


    /**
     * Wrapper for filter_var().
     * Filters a variable with a specified filter
     *
     * @link  http://www.php.net/manual/en/function.filter-var.php
     *
     * @param   mixed  $variable  Value to filter.
     * @param   int    $filter   ID of a filter to use (see http://www.php.net/manual/en/filter.filters.php).
     * @param   mixed  $options  Associative array of options or bitwise disjunction of flags. If filter
     *                           accepts options, flags can be provided in "flags" field of array. For the
     *                           "callback" filter, callback type should be passed. The callback must accept
     *                           one argument, the value to be filtered, and return the value after
     *                           filtering/sanitizing it.
     * @return  mixed  Returns the filtered data, or FALSE if the filter fails.
     */
    public function varItem($variable, $filter = FILTER_DEFAULT, $options = array())
    {
        return filter_var($variable, $filter, $options);
    }

}